'.\" t
.TH "cllockd" "1M" "Jun 26, 2006" "1\&.2\&.0"
.SH NAME
cllockd \- Linuxha.net Cluster Lock Daemon

.SH SYNOPSIS
.TS
l.
cllockd [\fB--config\fP \fIfile\fP] [\fB--verbose\fP] [\fB--detach\fP] [\fB--file\fP \fIf\fP]
        Start the cluster locking daemon

clockd \fB-?\fP
       Show brief usage information
.TE

.SH DESCRIPTION
This daemon is used to arbitrate access to resources on
the local machine on which it is running. Access to these resources
in a controlled manner to achieved by the programs that which to use a
particular resource requesting it via this daemon.

Thus a separate daemon runs on each node - usually started automatically 
when the cluster daemon on that node starts.

Currently there is only a limited number of resources, and programs 
that make use of this locking daemon - though the list is likely to
change as the software advances.

The cluster locking daemons runs on a TCP port defined by the 'clport'
element in the 'globals' section of the main cluster configuration file.
If such an element is missing the cluster daemon will not be started.

.SH ARGUMENTS
.TP 4
.B --config
This can be used to specify the name of an alternative configuration
file. Generally this functionality is only used for debugging and
development.
.TP
.B --verbose
Verbose mode - log informational messages that that just errors
and warnings.
.TP
.B --detach
Run as a true daemon by detaching the process from the current terminal
session. 
.TP
.B --file
Indicates the log file to use for appending messages to. 

.SH FILES
Typically this daemon is started by the \fIcldaemon(1M)\fP automatically.
In such cases it will start the process using the following arguments:

.TS
l.
--detach --verbose --file /var/log/cluster/cllockd.log
.TE

Since the locking daemon plays an important role when problems occur it
makes sense to ensure verbose logging is enabled. 

.SH USE OF '--nolocking' Option
It is possible to pass the \gB--nolocking\fP option to the \fIclform(1M)\fP
and \fIcldaemon(1M)\fP commands to stop them from attempting to start or
use a locking daemon. When this occurs the client start-up of applications
(whether they uses the \fB--nolocking\fP option or otherwise), will not attempt
to make use of locking - but otherwise will continue to function correctly.

If the locking daemon dies then users of the locks will fail to gain
connections and will issue warnings - but continue to work. This is because 
under 99% of circumstances this is the most suitable response. The administrator
can then start the daemon manually if desired.

.SH LOCK RETENTION PERIODS
When an application gains access to a lock that lock will be reserved
for them until they release it. If other programs request the same lock they
will be blocked until the resource is free.

If more than one program is waiting for a particular lock the order of
access to that lock is not defined - that is the response appears random
rather than a first-come first-serve basis.

If an application fails to release a lock then after a certain length of time
any other application requesting that lock will be given access to it. This
period typically defaults to 30 or 60 seconds depending on the lock. This
will ensure that deadlock can not occur since no lock can be held indefinitely.

If different retention periods are required, then the following configuration
file can be created/altered:

.TS
l.
/etc/cluster/cllocks.xml
.TE

For more information on the format of the file, please see the cllocks.xml(5)
manual page.

.SH SEE ALSO
.TS
l l.
clform(1M)	- High level cluster formation utility
clstartapp(1M)	- Low level application starting tool
clrunapp(1M)	- High level application starting tool
cldeamon(1M)	- Cluster status Daemon
clstat(1M)	- Show cluster status information (including locks)
clconf.xml(5)	- Overall cluster topology configuration file
cllocks.xml(5)	- Override built in locks or time-out settings
.TE

.SH AUTHOR
The \fIcllockd(1M)\fP utility was written by Simon Edwards, 2004-2006. The
author can be contacted via the website mentioned below.

.SH AVAILABILITY
This software is freely available from the Linuxha.net website - please see
\fBhttp://www.linuxha.net\fP for more details.

.SH WARRANTY
This is Open Source Software is per the GNU GPL. It is free to use and
distribute but \fIcomes with no warranty whatsoever\fP. For more information
on the license please see \fBwww.gnu.org/copyleft/gpl.html\fP.

